Chapter 3: continued

Running a UserTalk Script

When you first create a script, the most common way to run it is to click on the "Run" button. Remember: scripts that consist of an "on" definition that matches the name of the script must include the name of the script as an executable line at the end of the script. When you click "Run", Frontier first tries to compile the script. If there is a syntax error, it will present an error dialog. (Tip: if you select Copy while the error dialog is in front, the text of the error message will be put onto the clipboard.) Click the GoTo button in the error window; the cursor will be placed on the offending line. (If you are missing a quote mark, the cursor may appear on the following line.) To just check the syntax without running the script, click the "Compile" button. The "Debug" button is covered in the next section.

Any script can be treated as a "verb" and called from other places in the Object Database. In these cases, it's important to use the correct syntax for calling the script. The format for calling any script or verb is essentially the same: the "category" or location if necessary, the script name, parameters enclosed in parentheses -- or a pair of empty parentheses if there are no parameters. Scripts that are stored at the top level of your People table (e.g. people.ME.tester) can be called with just the name and parentheses; no "category" or location is required.

Scripts can be run using this complete name, as follows:

• from the Quick Script window
• from another script
• from a menu item
• in an outline window or Frontier "word processing" window

Most of these choices where covered earlier; the last item is new. Here's an example. Select "Open Notepad" from the "Custom" menu (or type Cmd-Y). Scroll to the end (if necessary) and type return to create a new line, then type the following:

msg ("Outlines are cool!")

Leave the cursor on that line and select "Run Selection" from the "UserLand" menu -- or use the keyboard equivalent of cmd-/. Your message appears in the main window and the "return value" of the message verb is placed as a comment on a new line indented below the line that contains your script. The Notepad or any other outline can be used like the Quick Script window, with the added advantage of keeping track of which scripts you ran and what result they returned. (The result of "msg" isn't very interesting but results are very important for many verbs.) In an outline, "Run Selection" really means to run the entire line (whether or not any of it is selected). "Run Selection" also works in Frontier's word processing windows, though the complete name must be selected and the result (the "return value") appears in the main window.

Debugging

Even after you fix syntax errors so that your script runs, it may not do what you intend. Frontier includes a powerful debugger to help pinpoint the source of the problem. Click the "Debug" button. Figure 6-3 shows the new buttons that appear.

Figure 6-3. Script-Execution Window Buttons

From left to right, these buttons permit you to do the following things while executing a script:

• "Step" enables you to walk through the execution of the script a statement at a time. When you click the button, it will run the current line and move the bar cursor (selection) to the next line. You can look at entries in the Object Database, examine variables in the program and perform other debugging tasks as needed before clicking "Step" again.
• "In" allows you to "dive" into a script that is being called by the script you are debugging. Click on this button while the cursor is positioned on a line in your script that calls a local or external script. If it's an external script, Frontier will open it in an editing window and position the cursor at its first executable line. You are still in debugging mode on the called script.
• "Out" has the effect of canceling one click of the "In" button. Essentially, it tells UserTalk, "Continue executing until you're out of this script and back at the level from which this script was called."
• "Follow" highlights each line of your script as it is executed but does not stop. A common use of "Follow" is to watch for lines or groups that are being skipped when you thought they should be executed. You can also watch the script and click "Stop" to pause the script when needed. (The debugger is pretty quick, so you may be better off setting a breakpoint, discussed below.)
• "Go" will run the script to completion -- unless you click "Stop" to pause. The "Go" button changes to "Stop" while the script is running.
• "Kill" terminates execution of the script immediately.
• "Lookup" permits you to examine the values of variables used in your script while the script is paused.

Figure 3-4 shows an example of using "Lookup". The script in the top window is paused in single-step mode. When the user clicks "Lookup", Frontier opens the temporary location in the Object Database where the script's local variables are stored while the script is running. In this case, the variable "answer" has a value of 3. As shown in the bottom window, the table looks like any other Frontier table. For complex scripts with many levels of testing, there are a whole series of tables. While a script is paused, you can navigate these tables just like you navigate any other table in Frontier.

Figure 3-4. Sample Variable Lookup

The "Lookup" button can also be used to jump to other places in the Object Database. Select any variable or function and click "Lookup"; Frontier will jump to that item if it exists.

There are times when stepping through a script a line at a time is too tedious to be of much value. For such situations, Frontier includes the ability to define a breakpoint on nearly any statement in your UserTalk scripts. When Frontier encounters a breakpoint during a "Debug" run, it stops processing unconditionally; all of the other circumstances of stepping, and moving into and out of subordinate scripts we discussed earlier are subordinate to this point. If you click "Run" instead of "Debug", or if you run the script from anywhere else in the Object Database, breakpoints will be ignored.

You set and clear breakpoints by selecting the line of interest and then choosing "Toggle Breakpoint" from the Script menu -- or pressing the Command-K keyboard equivalent. You can also Command-click on the line's item marker to toggle a breakpoint. When you set a breakpoint on a line, the leader character changes from a triangular shape to a hand:

You can also use other approaches to debugging UserTalk scripts, such as displaying in the Main Window messages indicating what part of a script is executing or the value of some variable you wish to monitor without interrupting script execution.

Reusable Code

If you have some object-oriented or other highly structured programming experience, the idea of designing code for reusability is not new to you. In fact, you can skip this section.

At the heart of UserTalk is a highly reusable set of verbs, each focussed on a particular task. You use these verbs over and over again in your scripts. You don't have to write the code for each verb in every script where you want to accomplish the particular task of that verb.

You should design your UserTalk scripts with the same goal in mind: each script performs a single task that can be isolated. When you need the same function in the future, you can re-use the code by calling (running) the earlier script from your new script.

There are two key benefits to "factoring" your code into single-purpose scripts. First, you can create new scripts more quickly because you can take advantage of code that already exists instead of writing it from scratch each time. Second, it is much easier to maintain your scripts. When you need to fix or improve the code that accomplishes a certain function, you can change it in one place. Every script that depends on it automatically gets the benefit of the new code.

It is also beneficial to minimize dependence on specific locations in the Object Database, sometimes by isolating this information within a single script. For example, if you're designing a suite that always opens a particular outline object for editing by the user, write one script whose job is to open that outline. Then, call this script from any other scripts that need to open the outline, rather than having them open the object directly. While this approach is slightly less efficient, it makes your suite much easier to maintain. If you change the location or name of the outline, you only have to change one line of UserTalk code; the other scripts will continue to work as expected.